.\" -*- nroff -*-
.TH ovsdb\-idlc 1 "November 2009" "Open vSwitch" "Open vSwitch Manual"
.ds PN ovsdb\-idlc
.
.SH NAME
ovsdb\-idlc \- Open vSwitch IDL (Interface Definition Language) compiler
.
.SH SYNOPSIS
\fBovsdb\-idlc \fBannotate\fI schema annotations\fR
.br
\fBovsdb\-idlc \fBc\-idl\-header\fI idl\fR
.br
\fBovsdb\-idlc \fBc\-idl\-source\fI idl\fR
.br
\fBovsdb\-idlc \-\-help\fR
.br
\fBovsdb\-idlc \-\-version\fR
.
.SH DESCRIPTION
The \fBovsdb\-idlc\fR program is a command-line tool for translating
Open vSwitch database interface definition language (IDL) schemas into
other formats.  It is used while building Open vSwitch, not at
installation or configuration time.  Thus, it is not normally
installed as part of Open vSwitch.
.
.PP
The \fIidl\fR files used as input for most \fBovsdb\-idlc\fR commands
have the same format as the OVSDB schemas, specified in the OVSDB
specification, with a few additions:
.
.IP "\fB""\fBidlPrefix\fR"" member of <database-schema>"
This member, which is required, specifies a string that is prefixed to
top-level names in C bindings.  It should probably end in an
underscore.
.
.IP "\fB""\fBidlHeader\fR"" member of <database-schema>"
This member, which is required, specifies the name of the IDL header.
It will be output on an \fB#include\fR line in the source file
generated by the C bindings.  It should include the bracketing
\fB""\fR or \fB<>\fR.
.
.SS "Commands"
.IP "\fBannotate\fI schema annotations\fR"
Reads \fIschema\fR, which should be a file in JSON format (ordinarily
an OVSDB schema file), then reads and executes the Python syntax
fragment in \fIannotations\fR.  The Python syntax fragment is passed
the JSON object as a local variable named \fBs\fR.  It may modify this
data in any way.  After the Python code returns, the object as
modified is re-serialized as JSON on standard output.
.
.IP "\fBc\-idl\-header\fI idl\fR"
Reads \fIidl\fR and prints on standard output a C header file that
defines a structure for each table defined by the schema.
.
.IP "\fBc\-idl\-source\fI idl\fR"
Reads \fIidl\fR and prints on standard output a C source file that
implements C bindings for the database defined by the schema.
.
.IP "\fBdoc\fI idl\fR"
Reads \fIidl\fR and prints on standard output a text file that
documents the schema.  The output may have very long lines, so it
makes sense to pipe it through, e.g. \fBfmt \-s\fR.
.
.SS "Options"
.so lib/common.man
.
.SH "BUGS"
\fBovsdb\-idlc\fR is more lenient about the format of OVSDB schemas
than other OVSDB tools.  It may successfully parse schemas that, e.g.,
\fBovsdb\-tool\fR rejects.
.
.SH "SEE ALSO"
The OVSDB specification.
